.\" Process this file with: groff -man -Tascii brickd.conf.5
.TH BRICKD.CONF 5 2017-10-11 Tinkerforge
.\" Turn off justification for nroff. Always turn off hyphenation.
.if n .ad l
.nh
.SH NAME
brickd.conf \- brickd(8) configuration file
.SH DESCRIPTION
The
.I brickd.conf
file specifies the configuration for the
.BR brickd (8)
program that routes Tinkerforge Protocol (TFP) messages between Tinkerforge
USB devices (Bricks) and sockets; plain TCP/IP sockets and WebSockets are
supported. For further information see the
.BR brickd (8)
manpage.
.SH "FILE FORMAT"
The file is line-based, each newline-terminated line represents either a
comment or parameter of the form "name = value". Leading and trailing
whitespace on a line is ignored.

Any line beginning with a hash (#) is ignored. But a hash in the middle of a
line is used as-is, therefore it is not possible to put a comment at the end
of a parameter. The hash and following text becomes part of the parameter.

Only the first equals sign (=) in a parameter is significant. Whitespace before
or after the first equals sign is discarded. Leading and trailing whitespace in
a parameter name is ignored. Leading and trailing whitespace in parameter value
is discarded. Internal whitespace within a parameter value is used as-is.

The values following the equals sign in parameters are all either strings (no
quotes needed) or integers.
.SH PARAMETERS
.SS Network Connectivity
The parameters with
.B listen
prefix control how
.BR brickd (8)
listens for incoming plain TCP/IP, WebSocket and special Mesh Gateway
connections.
.IP "\fBlisten.address\fR" 4
.BR brickd (8)
binds a plain TCP/IP socket and a WebSocket to this address to listen for
incoming plain TCP/IP and WebSocket connections. The address can either be a
dotted-decimal IPv4 address or a hexadecimal IPv6 address. It can also be a
hostname such as \fIlocalhost\fR. The default value is \fI0.0.0.0\fR.
.IP "\fBlisten.plain_port\fR" 4
The port number to listen to for incoming plain TCP/IP connections. The default
value is \fI4223\fR.
.IP "\fBlisten.websocket_port\fR" 4
The port number to listen to for incoming WebSocket connections. The default
value is \fI0\fR (disabled). To enable WebSocket support a port number different
from 0 has to be configured. The recommended port number is 4280. It is also
strongly recommend to enable authentication if WebSocket support is enabled.
.IP "\fBlisten.mesh_gateway_port\fR" 4
The port number to listen to for incoming Mesh Gateway connections from a WIFI
Extension 2.0 Mesh. The default value is \fI4240\fR.
.IP "\fBlisten.dual_stack\fR" 4
If a IPv6 address is given as
.B listen.address
or the hostname given as
.B listen.address
gets resolved to a IPv6 address then this option controls if dual-stack mode
gets enabled (\fIon\fR) or disabled (\fIoff\fR) on the socket bound to that
address. The default value is \fIoff\fR.
.SS Network Authentication
The Tinkerforge Protocol supports authentication on a per-connection basis.
By default authentication is disabled for backward compatibility. If it is
enabled then an IP Connection has to prove to
.BR brickd (8)
that it knows the authentication secret via a handshake mechanism, before it
can do any useful communication with Bricks and Bricklets.
.IP "\fBauthentication.secret\fR" 4
The authentication secret is an ASCII encoded string with up to 64 characters.
An empty secret means that authentication is disabled. If the secret is longer
than 64 characters then
.BR brickd (8)
will complain and refuse to start. The default value is an empty string
(disabled).
.SS Logging
Each log message of
.BR brickd (8)
has a certain severity level attached to it. The visibility of log messages is
controlled by their severity levels.
.IP "\fBlog.level\fR" 4
Log messages with a severity level above or equal to the configured level are
included in the log output, all other log messages are excluded.

Valid levels are \fIerror\fR, \fIwarn\fR, \fIinfo\fR and \fIdebug\fR. The
default value is \fIinfo\fR. It means that log messages on error, warn and info
level are shown, but messages on debug level are ignored. This can be
overridden with the
.B --debug
command line option of \fBbrickd\fR(8) that sets the severity level to
\fIdebug\fR.
.IP "\fBlog.debug_filter\fR" 4
If \fBlog.level\fR is set to \fIdebug\fR then the visibility of debug
messages can be controlled by a comma separated list of filter statements
(FIXME: Add more details about filter statements). The default value is an
empty string (all message are included).
.SH FILES
\fI/etc/brickd.conf\fR or \fI~/.brickd/brickd.conf\fR
.SH BUGS
Please report all bugs you discover to
\fI\%https://github.com/Tinkerforge/brickd/issues\fR
.SH AUTHOR
Matthias Bolte <matthias@tinkerforge.com>
.SH COPYRIGHT
Copyright (C) 2012-2018 Matthias Bolte
.SH LICENSE
brickd is distributed under the terms of the GNU GPL v2+. This is free
software; see the source for copying conditions. There is NO warranty;
not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.IR brickd (8)

For further information see \fI\%https://www.tinkerforge.com\fR
